Про документацию 1. Документация не поможет понять баг это или фича. a) Т.к. не факт что все крайние случаи учли и вы найдете ответ b) даже если документация говорит что это баг возможно сейчас этим уже пользуется 40-60% пользователей и это уже фича В любом случае в каждой такой ситуации это решение хотим ли далее мы это поддерживать или надо исключать этот сценарий (но это вообще не про то что написано в документации, тк это просто новое бизнес решение в текущих бизнес реалиях или поддерживать только для фиксированных клиентов через те же feature flag чтобы не плодить новые случаи итд итп). 2. Про пользовательские истории. Коротко: пишите функциональные / end2end тесты (если есть UI кликайте в UI, если есть API тыкайте в API и проверяйте на стенде с фиксированными данными типичные сценарии). В этом случае особенно ясно что тесты это документация которую можно выполнить и соответственно проверить актуальность. В тестах соответственно будет просто явно описан каждый бизнес кейс (это не про комбинаторику это именно про явные сценарии). Условно, что приложение поднялось и базовая функциональность не развалилась. Вся комбинаторика в тестах будет на модульном и интеграционном уровне (те ниже). Тратить время на извлечение из тикетов еще раз и вынос в вики бизнес сценариев это пустая трата времени (в сравнении с тестами). В любом случае есть wiki-страницы с базовым описанием продуктового запроса (есть тикеты (OKR + тикеты для конкретного сервиса итд) где в каждом описано какая проблема была и какое решение, коммиты со ссылками на тикеты итд). a) во-первых вы не знаете для кого пишете документацию с бизнес кейсами Это одна из основных проблем. Это может быть продуктолог, представитель заказчика, разработка, тестирование, тех поддержка итд. Для всех групп детализация и соответственно текст может быть разный (тк контекст разный). Те условно просто описать или сгенерировать документацию на публичный API (тк это просто описание ручек, сущностей, ошибок итд). C бизнес кейсами все могут хотеть разного и более того даже просто метафоры могут ехать (условно в коде название не в прямую соотносится с бизнес кейсом). Не надо напоминать про DDD, ситуации могут быть разные это просто пример что на разных уровнях метафоры могут различаться. b) как только вы начнете еще раз из тикетов выносить кучу текста (непонятно насколько детализированного), вы будете тратить время на поддержание консистентности (никакого тулинга толком нет, только возможно chatGPT в будущем). С тестами это произойдет само собой + инфраструктура тестов улучшиться и новые сценарии (в частности для воспроизведения странных кейсов баг или фича будет проще). Консистентость кучи текста непонятно для кого написанного и непонятно с каким уровнем детализации вы не удержите в итоге это будет вечно неполная, неактуальная документация и разочарования по этому поводу. 3. Про удивление почему нет большого желания писать документацию и почему это проблема. Во-первых не все любят аккуратно описывать технические вещи в принципе. Во-вторых опять-таки степень детализации и для кого и в каком формате писать неочевидна (это основной блокер и повод для фрустрации условно случайного разработчика) Более того, даже если один человек написал, другой запросто может быть недоволен как это написано вплоть до буквоедства. C end2end тестами вы просто кодом воспроизведете сценарий и напишите нужные assert с текстом собственно ожиданий (типа видимости кнопки или данных из базы \ запроса) (вариативность здесь гораздо меньше чем в случае текста). Также важно чтобы эти тесты писала разработка, тк тестирование может нагородить кучу кода которая в поддержке будет сложна (или просто по стилю разъезжаться с разработкой, или заново тестовые helper будут перепивать итд итп). Что работает: a) базовое readme (о чем проект вообще и что решает) b) документация по настройке окружения (развертывания) c) где логи, метрики итд d) общая архитектура (квадратики и стрелочки) e) ADR f) операционные cookbook (в том числе feature-flags как называются и на что влияют со ссылками на тикеты для контекста решаемых проблем) g) документация на API (условно swagger) Условно есть алерт X - какие шаги и куда смотреть если что. Все это меняется относительно редко и потому легко поддерживать (или для swagger\описания сущностей итд просто генерируется), более того это техническая информация. При это в любом случае есть a) тикеты (где в каждом есть явно сформулированная проблема + связанная тикеты, детали графиков, логов, стеков или описание продуктового запроса + явно решение коротко) b) продуктовые запросы в любом случае как правило описаны в wiki. Попытки поддерживать еще кучу текста с бизнес сценариями (в виду отсутствия формализации \ степени детализации, отсутствия автоматического контроля за консистентностью, сложностью даже поиска а где это написано и в каких формулировках и где продублировано просто как часть другой истории итд итп) не работают в принципе и вообще непонятно кому и зачем надо (в отличие от end2end тестов которые показывают автоматически работают сценарии или нет). Найти тех писателя который при должном уровне динамики в проекте будет за этим аккуратно следить тоже тот еще квест.
Привет, Юра! Приходи в чатик клуба - там можно похоливарить) 1. важно фиксировать как раз бизнес-требования в терминах бизнеса, и в первую очередь решаемые проблемы и задачи бизнеса, т.к. их часто вообще забывают сформулировать, а восстановить их из кода или даже из слишком низкоуровневой документации бывает невозможно. тогда от этого будет польза и не нужно будет переписывать в доку код со всеми нюансами. но кажется мы уже этот вопрос обсуждали много раз, и все так и остались при своих > это просто новое бизнес решение в текущих бизнес реалиях имхо, проще принимать решение менять бизнес процесс и бизнес требования, если старые описаны, а не приходится их додумывать из кода (что регулярно оказывается не только трудоёмко, но и нереально) 2. > В этом случае особенно ясно что тесты это документация которую можно выполнить и соответственно проверить актуальность. вообще звучит круто. у тебя есть опыт применения этой практики? если есть обязательно делись > В тестах соответственно будет просто явно описан каждый бизнес кейс (это не про комбинаторику это именно про явные сценарии). но это не закрывает потребности в описании решаемых проблем и задач бизнеса (или даже технических). а такие описания весьма ценны > В любом случае есть wiki-страницы с базовым описанием продуктового запроса тут не понял. откуда оно есть? я как раз ратую за то, что вот это очень важно иметь. вкупе со списком который ты ниже приводишь. по сути кроме adr по технике хочется ещё что-то такое же по бизнесу > С тестами это произойдет само собой ну вот я пока не понимаю, как это должно выглядеть и как работать. доку у меня более или менее пишут, и от неё есть определённая польза. тесты у нас тоже есть, но не e2e. юниты, функциональные и интеграционные определённо не заменяют документацию API и по бизнес процессам. а как собрать что-то прямо e2e я с трудом представляю. и тем более не понимаю, как тест, который какие-то кнопки в телефоне нажимает, заменит мне описание статусной модели торговой заявки на покупку акции, например 3. > Более того, даже если один человек написал, другой запросто может быть недоволен как это написано вплоть до буквоедства. то же верно и для кода, но вроде как-то справляемся. но в целом и правда есть проблема с тем чтобы писать полезное и не писать бесполезное. но это и к коду опять же относится - сложно разработчиков отучать писать бесполезные тонны оверинжинирнутого кода для решения гипотетических проблем. т.е. это проблема обучения > Что работает: это всё поддерживаю > g) документация на API (условно swagger) ну вот из сваггера часто сложно понять, как несколько ручек по порядку дёрнуть, чтобы полезный результат получить. и часто бывает даже не понятно, что всё это значит, без доп. комментариев общего характера. куда это записать? наверное можно как literate commented test с общим описанием текстом оформить, но я не видел удачных примеров, к сожалению > b) продуктовые запросы в любом случае как правило описаны в wiki. ага! так вот это и нужно. т.е. у тебя уже есть где-то такая дока, а ты мне говоришь, что она не нужна! > Попытки поддерживать еще кучу текста с бизнес сценариями так надо чуть-чуть текста уровня ридми и диаграммы взаимодействия или последовательностей какие-нибудь, т.е. > квадратики и стрелочки
я в целом понимаю страх протухания написанного текста. и тоже много раз видел, как это и правда происходит. но даже код с автоматически запускаемыми на нём тестами вполне себе протухает (видел прилично таких примеров), если им реально не пользуются и за актуальностью его и тестов не особо следят, а только пытаются успокоить CI. так что общего рецепта, как держать что-то свежим нет. и даже тесты не спасут. свежее будет только то, что реально используется и за чем следят
есть ещё такое наблюдение: если в человека, для доказательства своей позиции, кинуть ссылкой на доку, то он вероятно её прочтёт и может даже поймёт, а если на код (пусть даже тестов), то наверняка - нет. даже если это разработчик из соседней команды. хотя, конечно, всякое бывает
Про документацию
1. Документация не поможет понять баг это или фича.
a) Т.к. не факт что все крайние случаи учли и вы найдете ответ
b) даже если документация говорит что это баг возможно сейчас этим уже пользуется 40-60% пользователей и это уже фича
В любом случае в каждой такой ситуации это решение хотим ли далее мы это поддерживать или надо исключать этот сценарий (но это вообще не про то что написано в документации, тк это просто новое бизнес решение в текущих бизнес реалиях или поддерживать только для фиксированных клиентов через те же feature flag чтобы не плодить новые случаи итд итп).
2. Про пользовательские истории.
Коротко: пишите функциональные / end2end тесты (если есть UI кликайте в UI, если есть API тыкайте в API и проверяйте на стенде с фиксированными данными типичные сценарии).
В этом случае особенно ясно что тесты это документация которую можно выполнить и соответственно проверить актуальность.
В тестах соответственно будет просто явно описан каждый бизнес кейс (это не про комбинаторику это именно про явные сценарии).
Условно, что приложение поднялось и базовая функциональность не развалилась.
Вся комбинаторика в тестах будет на модульном и интеграционном уровне (те ниже).
Тратить время на извлечение из тикетов еще раз и вынос в вики бизнес сценариев это пустая трата времени (в сравнении с тестами).
В любом случае есть wiki-страницы с базовым описанием продуктового запроса (есть тикеты (OKR + тикеты для конкретного сервиса итд) где в каждом описано какая проблема была и какое решение, коммиты со ссылками на тикеты итд).
a) во-первых вы не знаете для кого пишете документацию с бизнес кейсами
Это одна из основных проблем.
Это может быть продуктолог, представитель заказчика, разработка, тестирование, тех поддержка итд.
Для всех групп детализация и соответственно текст может быть разный (тк контекст разный).
Те условно просто описать или сгенерировать документацию на публичный API (тк это просто описание ручек, сущностей, ошибок итд).
C бизнес кейсами все могут хотеть разного и более того даже просто метафоры могут ехать (условно в коде название не в прямую соотносится с бизнес кейсом).
Не надо напоминать про DDD, ситуации могут быть разные это просто пример что на разных уровнях метафоры могут различаться.
b) как только вы начнете еще раз из тикетов выносить кучу текста (непонятно насколько детализированного), вы будете тратить время на поддержание консистентности (никакого тулинга толком нет, только возможно chatGPT в будущем).
С тестами это произойдет само собой + инфраструктура тестов улучшиться и новые сценарии (в частности для воспроизведения странных кейсов баг или фича будет проще).
Консистентость кучи текста непонятно для кого написанного и непонятно с каким уровнем детализации вы не удержите в итоге это будет вечно неполная, неактуальная документация и разочарования по этому поводу.
3. Про удивление почему нет большого желания писать документацию и почему это проблема.
Во-первых не все любят аккуратно описывать технические вещи в принципе.
Во-вторых опять-таки степень детализации и для кого и в каком формате писать неочевидна (это основной блокер и повод для фрустрации условно случайного разработчика)
Более того, даже если один человек написал, другой запросто может быть недоволен как это написано вплоть до буквоедства.
C end2end тестами вы просто кодом воспроизведете сценарий и напишите нужные assert с текстом собственно ожиданий (типа видимости кнопки или данных из базы \ запроса)
(вариативность здесь гораздо меньше чем в случае текста).
Также важно чтобы эти тесты писала разработка, тк тестирование может нагородить кучу кода которая в поддержке будет сложна (или просто по стилю разъезжаться с разработкой, или заново тестовые helper будут перепивать итд итп).
Что работает:
a) базовое readme (о чем проект вообще и что решает)
b) документация по настройке окружения (развертывания)
c) где логи, метрики итд
d) общая архитектура (квадратики и стрелочки)
e) ADR
f) операционные cookbook (в том числе feature-flags как называются и на что влияют со ссылками на тикеты для контекста решаемых проблем)
g) документация на API (условно swagger)
Условно есть алерт X - какие шаги и куда смотреть если что.
Все это меняется относительно редко и потому легко поддерживать (или для swagger\описания сущностей итд просто генерируется), более того это техническая информация.
При это в любом случае есть
a) тикеты (где в каждом есть явно сформулированная проблема + связанная тикеты, детали графиков, логов, стеков или описание продуктового запроса + явно решение коротко)
b) продуктовые запросы в любом случае как правило описаны в wiki.
Попытки поддерживать еще кучу текста с бизнес сценариями (в виду отсутствия формализации \ степени детализации, отсутствия автоматического контроля за консистентностью, сложностью даже поиска а где это написано и в каких формулировках и где продублировано просто как часть другой истории итд итп) не работают в принципе и вообще непонятно кому и зачем надо (в отличие от end2end тестов которые показывают автоматически работают сценарии или нет).
Найти тех писателя который при должном уровне динамики в проекте будет за этим аккуратно следить тоже тот еще квест.
Спасибо, интересно!
Привет, Юра! Приходи в чатик клуба - там можно похоливарить)
1. важно фиксировать как раз бизнес-требования в терминах бизнеса, и в первую очередь решаемые проблемы и задачи бизнеса, т.к. их часто вообще забывают сформулировать, а восстановить их из кода или даже из слишком низкоуровневой документации бывает невозможно. тогда от этого будет польза и не нужно будет переписывать в доку код со всеми нюансами. но кажется мы уже этот вопрос обсуждали много раз, и все так и остались при своих
> это просто новое бизнес решение в текущих бизнес реалиях
имхо, проще принимать решение менять бизнес процесс и бизнес требования, если старые описаны, а не приходится их додумывать из кода (что регулярно оказывается не только трудоёмко, но и нереально)
2.
> В этом случае особенно ясно что тесты это документация которую можно выполнить и соответственно проверить актуальность.
вообще звучит круто. у тебя есть опыт применения этой практики? если есть обязательно делись
> В тестах соответственно будет просто явно описан каждый бизнес кейс (это не про комбинаторику это именно про явные сценарии).
но это не закрывает потребности в описании решаемых проблем и задач бизнеса (или даже технических). а такие описания весьма ценны
> В любом случае есть wiki-страницы с базовым описанием продуктового запроса
тут не понял. откуда оно есть? я как раз ратую за то, что вот это очень важно иметь. вкупе со списком который ты ниже приводишь. по сути кроме adr по технике хочется ещё что-то такое же по бизнесу
> С тестами это произойдет само собой
ну вот я пока не понимаю, как это должно выглядеть и как работать. доку у меня более или менее пишут, и от неё есть определённая польза. тесты у нас тоже есть, но не e2e. юниты, функциональные и интеграционные определённо не заменяют документацию API и по бизнес процессам. а как собрать что-то прямо e2e я с трудом представляю. и тем более не понимаю, как тест, который какие-то кнопки в телефоне нажимает, заменит мне описание статусной модели торговой заявки на покупку акции, например
3.
> Более того, даже если один человек написал, другой запросто может быть недоволен как это написано вплоть до буквоедства.
то же верно и для кода, но вроде как-то справляемся. но в целом и правда есть проблема с тем чтобы писать полезное и не писать бесполезное. но это и к коду опять же относится - сложно разработчиков отучать писать бесполезные тонны оверинжинирнутого кода для решения гипотетических проблем. т.е. это проблема обучения
> Что работает:
это всё поддерживаю
> g) документация на API (условно swagger)
ну вот из сваггера часто сложно понять, как несколько ручек по порядку дёрнуть, чтобы полезный результат получить. и часто бывает даже не понятно, что всё это значит, без доп. комментариев общего характера. куда это записать? наверное можно как literate commented test с общим описанием текстом оформить, но я не видел удачных примеров, к сожалению
> b) продуктовые запросы в любом случае как правило описаны в wiki.
ага! так вот это и нужно. т.е. у тебя уже есть где-то такая дока, а ты мне говоришь, что она не нужна!
> Попытки поддерживать еще кучу текста с бизнес сценариями
так надо чуть-чуть текста уровня ридми и диаграммы взаимодействия или последовательностей какие-нибудь, т.е.
> квадратики и стрелочки
ну и всякие статусные модели всякие. их хорошо бы, конечно, тоже описывать явно в коде и извлекать оттуда. но в целом руками нарисовать тоже вполне ок
я в целом понимаю страх протухания написанного текста. и тоже много раз видел, как это и правда происходит. но даже код с автоматически запускаемыми на нём тестами вполне себе протухает (видел прилично таких примеров), если им реально не пользуются и за актуальностью его и тестов не особо следят, а только пытаются успокоить CI. так что общего рецепта, как держать что-то свежим нет. и даже тесты не спасут. свежее будет только то, что реально используется и за чем следят
есть ещё такое наблюдение: если в человека, для доказательства своей позиции, кинуть ссылкой на доку, то он вероятно её прочтёт и может даже поймёт, а если на код (пусть даже тестов), то наверняка - нет. даже если это разработчик из соседней команды. хотя, конечно, всякое бывает